<div class="content">

  <h1>Simple Java Mail Features</h1>

  <section>
    <p class="wide">
      Upgrading to 5.0.0? Read the <a [routerLink]="['/migrate500']" simplePageScroll href="#navigation">migration notes</a>.
    </p>
  </section>

  <section class="introduction">
    <p class="wide">
      Creating and sending emails is very simple with Simple Java Mail; you don't need to know about the mailing RFC, MimeMessage or any other low
      level <code class="inline">javax.mail</code> API. No anonymous inner classes needed and no <a
      href="http://docs.spring.io/spring/docs/current/spring-framework-reference/html/mail.html">large frameworks</a> needed nor XML.
    </p>

    <p class="wide">
      On top of that, Simple Java Mail will do some basic validation checks so that your email is always populated with enough data. It even verifies
      email addresses against <a href="https://tools.ietf.org/html/rfc2822">RFC-2822</a> using the only complete <a
      href="https://github.com/bbottema/email-rfc2822-validator">rfc2822 validator in java</a> in the world.
    </p>

    <p class="wide">
      Simple Java Mail also takes care of all the
      <a href="https://javaee.github.io/javamail/docs/api/com/sun/mail/smtp/package-summary.html">connection and security properties</a> for you.
    </p>
  </section>

  <section class="toc">
    <ul>
      <li><a simplePageScroll href="#section-basic-usage">Basic usage</a></li>
       <li><a simplePageScroll href="#section-builder-api" class="indent">About the fluent API with the Builder pattern</a></li>
       <li><a simplePageScroll href="#section-reusable-mailer" class="indent">Configure once, reuse many times</a></li>
       <li><a simplePageScroll href="#section-add-recipients" class="indent">Alternative API for almost everything</a></li>
       <li><a simplePageScroll href="#section-sending-asynchronously" class="indent">Asynchronous parallel batch sending</a></li>
      <li><a simplePageScroll href="#section-custom-session">Sending with your own Session instance</a></li>
      <li><a simplePageScroll href="#section-custom-id">Setting a custom message ID on sent email</a></li>
      <li><a simplePageScroll href="#section-sent-id">Getting the generated email id after sending</a></li>
      <li><a simplePageScroll href="#section-ssl-tls">Sending with SSL and TLS</a></li>
        <li><a simplePageScroll href="#section-gmail" class="indent">SSL and TLS with Google mail</a></li>
      <li><a simplePageScroll href="#section-attachments">Adding attachments</a></li>
      <li><a simplePageScroll href="#section-embedding">Embedding images</a></li>
      <li><a simplePageScroll href="#section-custom-headers">Setting custom headers</a></li>
      <li><a simplePageScroll href="#section-custom-properties">Setting custom properties on the internal Session</a></li>
      <li><a simplePageScroll href="#section-session-access">Direct access to the internal Session</a></li>
      <li><a simplePageScroll href="#section-dkim">Signing emails with DKIM</a></li>
      <li><a simplePageScroll href="#section-return-receipt">Configure delivery / read receipt</a></li>
      <li><a simplePageScroll href="#section-email-validation">Validating Email Addresses</a></li>
      <li><a simplePageScroll href="#section-converting">Converting between email formats</a></li>
      <li><a simplePageScroll href="#section-bouncing-emails">Setting custom recipient for bouncing emails</a></li>
      <li><a simplePageScroll href="#section-reply-forward">Replying to and forwarding emails</a></li>
      <li><a simplePageScroll href="#section-proxy">Send using a proxy</a></li>
      <li><a simplePageScroll href="#section-connection-test">Testing a server connection</a></li>
    </ul>
  </section>

  <section class="roadmap">
    <h2>Roadmap</h2>
    <p>Currently everything we can think of is included!</p>
    <p>Got a suggestion? Please post it in the <a
      href="https://github.com/bbottema/simple-java-mail/issues"><strong>issue tracker</strong></a>.</p>
  </section>

  <a href="#section-basic-usage" id="section-basic-usage" class="section-link h2">&sect;</a>
  <h2>Basic usage</h2>

  <section>
    <div class="view">
      <p>
        Simply build an <code class="inline">Email</code>, populate it with your data, build a <code class="inline">Mailer</code> and send the Email
        instance. The mailer can be <a simplePageScroll
        href="#section-custom-session">created with your own <code class="inline">Session</code> instance as well</a>.
      </p>
      <p>
        A Mailer instance is reusable.
      </p>
    </div>

    <div class="side">
<pre><code>Email email = EmailBuilder.startingBlank()
    .from("Michel Baker", "m.baker@mbakery.com")
    .to("mom", "jean.baker@hotmail.com")
    .to("dad", "StevenOakly1963@hotmail.com")
    .withSubject("My Bakery is finally open!")
    .withPlainText("Mom, Dad. We did the opening ceremony of our bakery!!!")
    .buildEmail();

MailerBuilder
  .withSMTPServer("server", 25, "username", "password")
  .buildMailer()
  .sendMail(email);
</code></pre>
    </div>
  </section>


  <a href="#section-builder-api" id="section-builder-api" class="section-link h3">&sect;</a>
  <h3>About the fluent API with the Builder pattern</h3>

  <section>
    <p class="wide">
      The entry classes for the builders are EmailBuilder and MailerBuilder. For both, the first method affects the rest of the builder behavior.
    </p>
    <p class="wide">
      For <strong>EmailBuilder</strong>, the first method initializes the builder differently, either preconfiguring it
      (<code class="inline">EmailBuilder.copying()</code>, <code class="inline">EmailBuilder.replyingTo()</code>),
      or by setting values otherwise not possible
      (<code class="inline">EmailBuilder.forwarding()</code>).
    </p>
    <p class="wide">
      For <strong>MailerBuilder</strong>, the first method determines if you get a full builder API or a reduced API because you provided
      your own custom Session instance.<br/>
      <strong>If you provide your own session, a lot of properties are presumed to be preconfigured</strong>, such as SMTP server details.
    </p>
  </section>

  <a href="#section-reusable-mailer" id="section-reusable-mailer" class="section-link h3">&sect;</a>
  <h3>Configure once, reuse many times</h3>

  <section>
    <div class="view">
      <p>
        You can preconfigure a <code class="inline">Mailer</code> and use it many times.
      </p>
    </div>

    <div class="side">
<pre><code>Mailer inhouseMailer = MailerBuilder
    .withSMTPServer("server", 25, "username", "password")
    .buildMailer();

inhouseMailer.sendMail(email);
inhouseMailer.sendMail(anotherEmail);
</code></pre>
      Or as preconfigured Spring bean:
      <pre><code>@Bean
public Mailer inhouseMailer() {{ '{' }}
        return MailerBuilder
            .withSMTPServer(...)
            .buildMailer();
{{ '}' }}
</code></pre>
      Or the default one from Spring support:
      <pre><code>
@Import(SimpleJavaMailSpringSupport.class)

@Autowired Mailer mailer; // configured completely using default properties
</code></pre>
    </div>
  </section>


  <a href="#section-add-recipients" id="section-add-recipients" class="section-link h3">&sect;</a>
  <h3>Alternative API for almost everything</h3>

  <section>
    <div>
      <p class="wide">
        Simple Java Mail has alternative ways to do things for almost everything...
      </p>
      <p class="wide">
        For example, when building an email, you can add recipients using
        <a href="https://github.com/bbottema/simple-java-mail/blob/master/src/main/java/org/simplejavamail/email/Recipient.java"><code class="inline">Recipient</code></a>
        objects, <a href="">RFC822 compiant <code class="inline">String</code> addresses</a> (each can be comma delimited and include optional nested names),
        <a href="http://geronimo.apache.org/maven/specs/geronimo-javamail_1.4_spec/1.6/apidocs/javax/mail/internet/InternetAddress.html"><code class="inline">InternetAddress</code></a>
        objects, collections of said addresses, default address names or fixed address names.
      </p>
    </div>

    <div>
      <pre><code>// You can add your own Recipient instances for example
currentEmailBuilder.withRecipients(yourRecipient1, yourRecipient2...);</code></pre>

      <pre><code>// or add comma / semicolon separated addresses (without names)
String list = "twister@sweets.com,blue.tongue@sweets.com;honey@sweets.com";
currentEmailBuilder.bcc(list);</code></pre>
      <pre><code>// or:
currentEmailBuilder.bccWithDefaultName("maintenance group", list);
currentEmailBuilder.bccWithFixedName("maintenance group", list); // same as .bcc()</code></pre>

      <pre><code>// what about a group with one deviating name?
String list = "bob@sweets.com, gene@sweets.com; Security Group &lt;security@sweets.com&gt;";
currentEmailBuilder.toWithDefaultName("stakeholders", list);
// bob and gene are named "stakeholders", "Security Group" get its own name</code></pre>
      <p>Through properties:</p>
      <pre><code class="language-properties">simplejavamail.defaults.bcc.name=
simplejavamail.defaults.bcc.address=twister@sweets.com,blue.tongue@sweets.com;honey@sweets.com
</code></pre>
    </div>

    <div>
      <div class="view">
        <p>To give you an idea of how flexible the API is for adding recipients:</p>
      </div>
      <div class="side">
      <pre><code class="small">// TO
.to(Recipient... recipients)
.to(Collection&lt;Recipient&gt; recipients)
.to(String name, String address)
.to(String oneOrMoreAddresses)
.to(String name, String... oneOrMoreAddressesEach)
.to(String name, Collection&lt;String&gt; oneOrMoreAddressesEach)
.toMultiple(String... oneOrMoreAddressesEach)
.toMultiple(Collection&lt;String&gt; oneOrMoreAddressesEach)
.toWithFixedName(String name, String... oneOrMoreAddressesEach)
.toWithDefaultName(String name, String... oneOrMoreAddressesEach)
.toWithFixedName(String name, Collection&lt;String&gt; oneOrMoreAddressesEach)
.toWithDefaultName(String name, Collection&lt;String&gt; oneOrMoreAddressesEach)
.to(String name, InternetAddress address)
.to(InternetAddress address)
.to(String name, InternetAddress... oneOrMoreAddressesEach)
.toAddresses(String name, Collection&lt;InternetAddress&gt; oneOrMoreAddressesEach)
.toMultiple(InternetAddress... oneOrMoreAddressesEach)
.toMultipleAddresses(Collection&lt;InternetAddress&gt; oneOrMoreAddressesEach)
.toAddressesWithFixedName(String name, InternetAddress... oneOrMoreAddressesEach)
.toAddressesWithDefaultName(String name, InternetAddress... oneOrMoreAddressesEach)
.toAddressesWithFixedName(String name, Collection&lt;InternetAddress&gt; oneOrMoreAddressesEach)
.toAddressesWithDefaultName(String name, Collection&lt;InternetAddress&gt; oneOrMoreAddressesEach)
// CC
.cc(Recipient... recipients)
.cc(Collection&lt;Recipient&gt; recipients)
.cc(String name, String address)
.cc(String oneOrMoreAddresses)
.cc(String name, String... oneOrMoreAddressesEach)
.cc(String name, Collection&lt;String&gt; oneOrMoreAddressesEach)
.ccMultiple(String... oneOrMoreAddressesEach)
.ccAddresses(Collection&lt;String&gt; oneOrMoreAddressesEach)
.ccWithFixedName(String name, String... oneOrMoreAddressesEach)
.ccWithDefaultName(String name, String... oneOrMoreAddressesEach)
.ccWithFixedName(String name, Collection&lt;String&gt; oneOrMoreAddressesEach)
.ccWithDefaultName(String name, Collection&lt;String&gt; oneOrMoreAddressesEach)
.cc(String name, InternetAddress address)
.cc(InternetAddress address)
.cc(String name, InternetAddress... oneOrMoreAddressesEach)
.ccAddresses(String name, Collection&lt;InternetAddress&gt; oneOrMoreAddressesEach)
.ccMultiple(InternetAddress... oneOrMoreAddressesEach)
.ccMultipleAddresses(Collection&lt;InternetAddress&gt; oneOrMoreAddressesEach)
.ccAddressesWithFixedName(String name, InternetAddress... oneOrMoreAddressesEach)
.ccAddressesWithDefaultName(String name, InternetAddress... oneOrMoreAddressesEach)
.ccAddressesWithFixedName(String name, Collection&lt;InternetAddress&gt; oneOrMoreAddressesEach)
.ccAddressesWithDefaultName(String name, Collection&lt;InternetAddress&gt; oneOrMoreAddressesEach)
// BCC
.bcc(Recipient... recipients)
.bcc(Collection&lt;Recipient&gt; recipients)
.bcc(String name, String address)
.bcc(String oneOrMoreAddresses)
.bcc(String name, String... oneOrMoreAddressesEach)
.bcc(String name, Collection&lt;String&gt; oneOrMoreAddressesEach)
.bccMultiple(String... oneOrMoreAddressesEach)
.bccAddresses(Collection&lt;String&gt; oneOrMoreAddressesEach)
.bccWithFixedName(String name, String... oneOrMoreAddressesEach)
.bccWithDefaultName(String name, String... oneOrMoreAddressesEach)
.bccWithFixedName(String name, Collection&lt;String&gt; oneOrMoreAddressesEach)
.bccWithDefaultName(String name, Collection&lt;String&gt; oneOrMoreAddressesEach)
.bcc(String name, InternetAddress address)
.bcc(InternetAddress address)
.bcc(String name, InternetAddress... oneOrMoreAddressesEach)
.bccAddresses(String name, Collection&lt;InternetAddress&gt; oneOrMoreAddressesEach)
.bccMultiple(InternetAddress... oneOrMoreAddressesEach)
.bccMultipleAddresses(Collection&lt;InternetAddress&gt; oneOrMoreAddressesEach)
.bccAddressesWithFixedName(String name, InternetAddress... oneOrMoreAddressesEach)
.bccAddressesWithDefaultName(String name, InternetAddress... oneOrMoreAddressesEach)
.bccAddressesWithFixedName(String name, Collection&lt;InternetAddress&gt; oneOrMoreAddressesEach)
.bccAddressesWithDefaultName(String name, Collection&lt;InternetAddress&gt; oneOrMoreAddressesEach)
// GENERIC
.withRecipientsWithDefaultName(String defaultName, Collection&lt;String&gt; oneOrMoreAddressesEach, RecipientType recipientType)
.withRecipientsWithFixedName(String fixedName, Collection&lt;String&gt; oneOrMoreAddressesEach, RecipientType recipientType)
.withRecipientsWithDefaultName(String name, RecipientType recipientType, String... oneOrMoreAddressesEach)
.withRecipientsWithFixedName(String name, RecipientType recipientType, String... oneOrMoreAddressesEach)
.withRecipients(String name, boolean fixedName, RecipientType recipientType, String... oneOrMoreAddressesEach)
.withRecipients(String name, boolean fixedName, Collection&lt;String&gt; oneOrMoreAddressesEach, RecipientType recipientType)
.withAddressesWithDefaultName(String defaultName, Collection&lt;InternetAddress&gt; addresses, RecipientType recipientType)
.withAddressesWithFixedName(String fixedName, Collection&lt;InternetAddress&gt; addresses, RecipientType recipientType)
.withAddresses(String name, boolean fixedName, Collection&lt;InternetAddress&gt; addresses, RecipientType recipientType)
.withRecipients(Collection&lt;Recipient&gt; recipients)
.withRecipients(Recipient... recipients)
.withRecipients(Collection&lt;Recipient&gt; recipients, RecipientType fixedRecipientType)
.withRecipient(String singleAddress, RecipientType recipientType)
.withRecipient(String name, String singleAddress, RecipientType recipientType)
.withRecipient(Recipient recipient)</code></pre>
      </div>
    </div>
  </section>


  <a href="#section-sending-asynchronously" id="section-sending-asynchronously" class="section-link h3">&sect;</a>
  <h3>Asynchronous parallel batch sending</h3>

  <section>
    <div class="view">
      <p>
        The default mode is to send emails synchronously, blocking execution until the email was processed completely and the STMP server sent a
        succesful result.
      </p>
      <p>
        You can also send anyschronously in parallel or batches, or simply send in a fire-and-forget way. If an authenticated proxy is used, the <a
        simplePageScroll href="#section-proxy">proxy bridging server</a> is kept alive until the last email has been sent.</p>
      <p>
        Depending on the SMTP server (and proxy server if used) this can greatly influence how fast emails are sent.
      </p>
    </div>

    <div class="side">
<pre><code>mailer.sendMail(email, /* async = */ true);
</code></pre>
      <p>Refer to the <a simplePageScroll [routerLink]="['/configuration']" href="#section-programmatic-api-other">configuration section</a>
         on how to set the thread pool size default.</p>
    </div>
  </section>


  <a href="#section-custom-session" id="section-custom-session" class="section-link h2">&sect;</a>
  <h2>Sending with your own Session instance</h2>

  <section>
    <div class="view">
      <p>
        If you prefer to use your own preconfigured <code class="inline">Session</code> instance and still benefit from Simple Java Mail, you can!
      </p>
    </div>

    <div class="side">
<pre><code>Email email = ...
...

MailerBuilder
    .usingSession(yourSession)
    .buildMailer()
    .sendMail(email);
</code></pre>
    </div>
  </section>


  <a href="#section-custom-id" id="section-custom-id" class="section-link h2">&sect;</a>
  <h2>Setting a custom message ID on sent email</h2>

  <section>
    <div class="view">
      <p>Message id's are normally generated by the underlying JavaMail framework, but you can provide your own if required.</p>
      <p>Just make sure your own id's conform to the <a href="https://tools.ietf.org/html/rfc5322#section-3.6.4">rfc5322</a> msg-id format standard</p>
    </div>

    <div class="side">
<pre><code>currentEmailBuilder.fixingMessageId("<123@456>");
</code></pre>
    </div>
  </section>


  <a href="#section-sent-id" id="section-sent-id" class="section-link h2">&sect;</a>
  <h2>Getting the generated email id after sending</h2>

  <section>
    <div class="view">
      <p>
        Sometimes you need the actual ID used in the MimeMessage that went out to the SMTP server.
        Luckily, it's very easy to retrieve it.
      </p>
    </div>

    <div class="side">
<pre><code>
mailer.sendMail(email); // id updated during sending!
email.getId(); // <1420232606.6.1509560747190@Cypher>
</code></pre>
    </div>
  </section>


  <a href="#section-ssl-tls" id="section-ssl-tls" class="section-link h2">&sect;</a>
  <h2>Sending with SSL and TLS</h2>

  <section>
    <div class="view">
      <p>
        Activating SSL or TLS is super easy. Just use the appropriate <code class="inline">TransportStrategy</code> enum.
      </p>
    </div>

    <div class="side">
<pre><code class="small">Email email = ...;

MailerBuilder.withTransportStrategy(TransportStrategy.SMTP); // default if omitted
MailerBuilder.withTransportStrategy(TransportStrategy.SMTPS);
MailerBuilder.withTransportStrategy(TransportStrategy.SMTP_TLS);
</code></pre>
    </div>
  </section>


  <a href="#section-gmail" id="section-gmail" class="section-link h3">&sect;</a>
  <h3>SSL and TLS with Google mail</h3>

  <section>
    <div class="view">
      <p>
        Here's an example of SSL and TLS using gMail.
      </p>
      <p>
        If you have two-factor login turned on, you need to generate an <a href="https://security.google.com/settings/security/apppasswords">application
                                                                                                                                             specific
                                                                                                                                             password</a>
        from your Google account.
      </p>
    </div>

    <div class="side">
<pre><code>MailerBuilder
  .withSMTPServer("smtp.gmail.com", 25, "your user", "your password")
  .withTransportStrategy(TransportStrategy.SMTP_TLS)
  // or
  .withSMTPServer("smtp.gmail.com", 587, "your user", "your password")
  .withTransportStrategy(TransportStrategy.SMTP_TLS)
  // or
  .withSMTPServer("smtp.gmail.com", 465, "your user", "your password")
  .withTransportStrategy(TransportStrategy.SMTPS);
</code></pre>
    </div>
  </section>


  <a href="#section-attachments" id="section-attachments" class="section-link h2">&sect;</a>
  <h2>Adding attachments</h2>

  <section>
    <div class="view">
      <p>
        You can add attachments very easily, but you'll have to provide the data yourself. Simple Java Mail accepts <code class="inline">byte[]</code>
        and <code class="inline">DataSource</code> objects.
      </p>
    </div>

    <div class="side">
<pre><code class="small">currentEmailBuilder
    .withAttachment("dresscode.txt", new ByteArrayDataSource("Black Tie Optional", "text/plain"))
    .withAttachment("location.txt", "On the moon!".getBytes(Charset.defaultCharset()), "text/plain")
    // ofcourse it can be anything: a pdf, doc, image, csv or anything else
    .withAttachment("invitation.pdf", new FileDataSource("invitation_v8.3.pdf"))
</code></pre>
    </div>
  </section>


  <a href="#section-embedding" id="section-embedding" class="section-link h2">&sect;</a>
  <h2>Embedding images</h2>

  <section>
    <div class="view">
      <p>
        Embedding images is simple, but you have to add the placeholders in the HTML yourself.
      </p>
    </div>

    <div class="side">
<pre><code class="small">currentEmailBuilder.withEmbeddedImage("smiley", new FileDataSource("smiley.jpg"));
// this example is included in the demo package in MailTestApp.java
String base64String = "iVBORw0KGgoAAAANSUhEUgAAA ...snip";
currentEmailBuilder.withEmbeddedImage("thumbsup", parseBase64Binary(base64String), "image/png");

// the corresponding HTML should contain the placeholders
&lt;p&gt;Let&#39;s go!&lt;/p&gt;&lt;img src=&#39;cid:thumbsup&#39;&gt;&lt;br/&gt;
&lt;p&gt;Smile!&lt;/p&gt;&lt;img src=&#39;cid:smiley&#39;&gt;
</code></pre>
    </div>
  </section>


  <a href="#section-custom-headers" id="section-custom-headers" class="section-link h2">&sect;</a>
  <h2>Setting custom headers</h2>

  <section>
    <div class="view">
      <p>
        Sometimes you need extra headers in your email because your email server, recipient server or your email client needs it. Or perhaps you have
        a proxy or monitoring setup in between mail servers. Whatever the case, adding headers is easy.
      </p>
    </div>

    <div class="side">
<pre><code>currentEmailBuilder
    .withHeader("X-Priority", 2);
    .withHeader("X-MC-GoogleAnalyticsCampaign", "halloween_sale");
    .withHeader("X-MEETUP-RECIP-ID", "71415272");
    .withHeader("X-my-custom-header", "foo");
    // or
    .withHeaders(yourHeadersMap);
</code></pre>
    </div>
  </section>


  <a href="#section-custom-properties" id="section-custom-properties" class="section-link h2">&sect;</a>
  <h2>Setting custom properties on the internal Session</h2>

  <section>
    <div class="view">
      <p>
        In case you need to modify the internal Session object itself, because you need a tailored configuration that is supported by the underlying
        <code class="inline">javax.mail</code>, that too is very easy.
      </p>
    </div>

    <div class="side">
<pre><code>currentMailerBuilder
    .withProperty("mail.smtp.timeout", 30 * 1000)
    .withProperty("mail.smtp.connectiontimeout", 10 * 1000)
    // or
    .withProperties(yourPropertiesObject)
    .withProperties(yourPropertiesMap)
</code></pre>
    </div>
  </section>


  <a href="#section-session-access" id="section-session-access" class="section-link h2">&sect;</a>
  <h2>Direct access to the internal Session</h2>

  <section>
    <div class="view">
      <p>
        For emergencies, you can also get a hold of the internal Session instance itself. <strong>You should never need this however</strong> and if
        you do it means Simple Java Mail failed to simplify the configuration process for you. <strong>Please let us know how we can help alleviate
                                                                                                       this need</strong>.
      </p>
    </div>

    <div class="side">
<pre><code>Mailer mailer = ...;

Session session = mailer.getSession();
// do your thing with session
</code></pre>
    </div>
  </section>


  <a href="#section-dkim" id="section-dkim" class="section-link h2">&sect;</a>
  <h2>Signing emails with DKIM</h2>

  <section>
    <div class="view">
      <p>
        Simple Java Mail also supports signing with <a href="http://blog.endpoint.com/2014/04/spf-dkim-and-dmarc-brief-explanation.html">DKIM</a>
        domain keys. It uses <a href="https://github.com/markenwerk/java-utils-mail-dkim">java-utils-mail-dkim</a> (dependency packaged along) to
        perform the DNS DKIM record check on the given domain.
      </p>
      <p>DKIM is an optional feature and if you want to use it, you need to include the following dependency in your project:</p>
      <pre><code class="small language-xml">&lt;dependency&gt;
    &lt;groupId&gt;net.markenwerk&lt;/groupId&gt;
    &lt;artifactId&gt;utils-mail-dkim&lt;/artifactId&gt;
    &lt;version&gt;X.X.X&lt;/version&gt;
&lt;/dependency&gt;</code></pre>
    </div>

    <div class="side">
<pre><code>currentEmailBuilder.
    .signWithDomainKey(
       privateKey byte[] / File / InputStream,
       "your_domain.org",
       "your_selector");

mailer.sendMail(signedEmail);
</code></pre>
      You can also directly use the helper method:
      <pre><code>Mailer.signMessageWithDKIM(mimeMessageToSign, emailContainingSigningDetails);</code></pre>
    </div>
  </section>


  <a href="#section-return-receipt" id="section-return-receipt" class="section-link h2">&sect;</a>
  <h2>Configure delivery / read receipt</h2>

  <section>
    <div class="view">
      <p>
        For servers and clients that support it (mostly Outlook at offices), Simple Java Mail has built in support for
        <a href="https://www.chilkatsoft.com/p/p_313.asp">'delivery receipt' and 'read receipt'</a>, which is configured
        through the headers <code>Return-Receipt-To</code> and <code>Disposition-Notification-To</code> respectively.
      </p>
      <p>
        You can explicitly define the email address to return the receipts to or else Simple Java Mail will default
        to the <em>replyTo</em> address if available or else the <em>fromAddress</em>.
      </p>
    </div>

    <div class="side">
<pre><code class="small">currentEmailBuilder.
    .withDispositionNotificationTo();
    .withReturnReceiptTo();
    // or:
    .withDispositionNotificationTo(new Recipient("name", "address@domain.com"));
    .withReturnReceiptTo(new Recipient("name", "address@domain.com"));
</code></pre>
    </div>
  </section>


  <a href="#section-email-validation" id="section-email-validation" class="section-link h2">&sect;</a>
  <h2>Validating Email Addresses</h2>

  <section>
    <div class="view">
      <p>
        Simple Java Mail can validate your email addresses. It's not just a simple regex check, but a complete and robust full validation against <a
        href="https://tools.ietf.org/html/rfc2822">RFC-2822</a>. It does this by including <a
        href="https://github.com/bbottema/email-rfc2822-validator">email-rfc2822-validator</a> in the library.
      </p>
      <p>
        Address validation is performed automatically when sending emails, but you can also directly perform validations.
      </p>
    </div>

    <div class="side">
<pre><code>currentMailerBuilder
    .withEmailAddressCriteria(EmailAddressCriteria.RFC_COMPLIANT)
    // or
    .withEmailAddressCriteria(
      of(ALLOW_QUOTED_IDENTIFIERS, ALLOW_PARENS_IN_LOCALPART)
    )
    // or
    .clearEmailAddressCriteria() // turn off validation
    .resetEmailAddressCriteria() // reset to default
</code></pre>
      <pre><code>// you can also directly perform validations.
mailer.validate(email);

// or use the underlying library included for this
EmailAddressValidator.isValid("your_address@domain.com",
   EmailAddressCriteria.RFC_COMPLIANT);

// or, fine-tuned to be less strict:
EmailAddressValidator.isValid("your_address@domain.com",
   of(ALLOW_QUOTED_IDENTIFIERS, ALLOW_PARENS_IN_LOCALPART));
</code></pre>
    </div>
  </section>



  <a href="#section-generate-converting" id="section-converting" class="section-link h2">&sect;</a>
  <h2>Converting between, Email, MimeMessage, EML and Outlook .msg</h2>

  <section>
    <div class="view">
      <p>
        With Simple Java Mail you can easily convert to other types.
      </p>
      <p>
        For example, if you need a MimeMessage, you can convert <code class="inline">Email</code> objects, EML data and even Outlook .msg files.
      </p>
      <p>
        If you already have a MimeMessage, you can it into an Email instance, complete with embedded images and attachments, headers intact.
      </p>
      <p>
         You can even build a mass Outlook .msg to <a href="http://forensicswiki.org/wiki/EML">EML</a> converter if you like!
      </p>
    </div>

    <div class="side">
<pre><code class="small">// from Email
String eml =              EmailConverter.emailToEML(yourEmail);
MimeMessage mimeMessage = EmailConverter.emailToMimeMessage(yourEmail);
MimeMessage mimeMessage = EmailConverter.emailToMimeMessage(yourEmail, yourSession);

// from MimeMessage
Email email =             EmailConverter.mimeMessageToEmail(yourMimeMessage);
String eml =              EmailConverter.mimeMessageToEML(yourMimeMessage);

// from EML
Email email =             EmailConverter.emlToEmail(emlDataString);
MimeMessage mimeMessage = EmailConverter.emlToMimeMessage(emlDataString);
MimeMessage mimeMessage = EmailConverter.emlToMimeMessage(emlDataString, yourSession);

// from Outlook .msg
Email email =             EmailConverter.outlookMsgToEmail(readToString("yourMessage.msg"));
Email email =             EmailConverter.outlookMsgToEmail(new File("yourMessage.msg"));
Email email =             EmailConverter.outlookMsgToEmail(getInputStream("yourMessage.msg"));
String eml =              EmailConverter.outlookMsgToEML(readToString("yourMessage.msg"));
String eml =              EmailConverter.outlookMsgToEML(new File("yourMessage.msg"));
String eml =              EmailConverter.outlookMsgToEML(getInputStream("yourMessage.msg"));
MimeMessage mimeMessage = EmailConverter.outlookMsgToMimeMessage(readToString("yourMessage.msg"));
MimeMessage mimeMessage = EmailConverter.outlookMsgToMimeMessage(new File("yourMessage.msg"));
MimeMessage mimeMessage = EmailConverter.outlookMsgToMimeMessage(getInputStream("yourMessage.msg"));
</code></pre>
    </div>
  </section>


  <a href="#section-bouncing-emails" id="section-bouncing-emails" class="section-link h2">&sect;</a>
  <h2>Setting custom recipient for bouncing emails</h2>

  <section>
    <div class="view">
      <p>
        For bouncing emails, you can provide a hint to the SMTP server to which bouncing emails should be returned.
        This is also known as the Return-Path or Envelope FROM and is set on the Session instance with the property
        <code class="inline">mail.smtp.from</code>.
      </p>
      <p>
        Simple Java Mail offers a convenience method to set this property.
      </p>
    </div>

    <div class="side">
<pre><code>// in similar fashion to setting replyTo address:
currentEmailBuilder
    .withBounceTo(aRecipientInstance) // or
    .withBounceTo("Bob", "bob.techdesk@candyshop.com")
    // or using one of the many alternative methods...
</code></pre>
    </div>
  </section>


  <a href="#section-reply-forward" id="section-reply-forward" class="section-link h2">&sect;</a>
  <h2>Replying to and forwarding emails</h2>

  <section>
    <div class="view">
      <p>
        If you have an email you want to reply to or wish to forward, the <code class="inline">EmailBuilder</code>
        has you covered.
      </p>
      <br />
      <div>
        <p>
          <strong>Note:</strong> due to the nature of the underlying JavaMail framework (also see
            <a href="https://javaee.github.io/javamail/FAQ#reply">reply</a> /
            <a href="https://javaee.github.io/javamail/FAQ#forward">forward</a>):
        </p>
        <ul class="indent">
          <li>In case of replying, the original email is quoted in the body of the reply itself.</li>
          <li>In case of forwarding, the original email is included as a separate body inside the forward.</li>
        </ul>
      </div>
    </div>

    <div class="side">
      <p>Replying to an email:</p>
<pre><code>EmailBuilder
    .replyingTo(receivedEmail) // Email or MimeMessage
    .from("dummy@domain.com")
    .prependText("Reply body. Original email included below")
    .buildEmail();
</code></pre>
      <p>Forwarding an email:</p>
<pre><code>EmailBuilder
    .forwarding(receivedEmail) // Email or MimeMessage
    .from("dummy@domain.com")
    .text("Hello? This is Forward. See below email:")
    .buildEmail();
</code></pre>
    </div>
  </section>


  <a href="#section-proxy" id="section-proxy" class="section-link h2">&sect;</a>
  <h2>Send using a proxy</h2>

  <section>
    <div>
      <p class="wide">
        Simple Java Mail supports sending emails through a proxy. It is also the only java mailing framework in the world that supports sending emails
        through <strong>authenticated</strong> proxies. The reason for this is that the underlying native
        <a href="https://java.net/projects/javamail/pages/Home">Javax Mail framework</a> supports anonymous SOCKS5 proxies, but
        <a href="http://www.oracle.com/technetwork/java/javamail/faq/index.html#proxy">not authenticated proxies</a>.
      </p>
      <p class="wide">
        To make this work with authentication, Simple Java Mail uses a trick: it sets up a temporary anonymous proxy server for Javax Mail to connect
        to and then the bridge relays the connection to the target proxy performing the authentication outside of Javax Mail.
      </p>
      <p class="wide">
        This temporary server is referred to as the <strong>Proxy Bridging Server</strong>.
      </p>
    </div>

    <div>
<pre><code>// anonymous proxy
currentMailerBuilder.withProxy("proxy.host.com", 1080)

// authenticated proxy
currentMailerBuilder.withProxy("proxy.host.com", 1080, "proxy username", "proxy password");
</code></pre>
      <p>Refer to the <a simplePageScroll [routerLink]="['/configuration']" href="#section-other-settings">configuration section</a>
         on how to set proxy server defaults and the port on which the proxy bridge runs.</p>
    </div>
  </section>


  <a href="#section-connection-test" id="section-connection-test" class="section-link h2">&sect;</a>
  <h2>Testing a server connection</h2>

  <section>
    <div>
      <p class="wide">
        If you just want to do a connection test using your current configuration, including transport strategy and (authenticated)
        proxy, Simple Java Mail got you covered.
      </p>
    </div>

    <div>
<pre><code>// configure your mailer
Mailer mailer = ...;

// perform connection test
mailer.testConnection(); // no error means success
</code></pre>
    </div>
  </section>

</div>
